Move sorting functions and add to readme

diff --git a/README.org b/README.org
index 2e3231f1cffd352253aa1e451dc0702c33b74d8e..10df9b07c7594f7483d234a6dc8d2b5455ffde50 100644 (file)
--- a/README.org
+++ b/README.org
@@ -290,19 +290,22 @@ By default the output is sorted by the key in a custom order. The default order
 is to sort lexicographically within each "class" of key, where the classes and
 their order are
 
-=Special (SPC, TAB, ...) < Single Character (a, ...) < Modifier (C-, M-, ...) < Other=
+=Special (SPC, TAB, ...) < Single Character (ASCII) (a, ...) < Modifier (C-, M-, ...) < Other=
 
-You can control the order by setting this variable. 
+You can control the order by setting this variable. This also shows the other
+available options.
 
 #+BEGIN_SRC Emacs-lisp
+;; default
 (setq which-key-sort-order 'which-key-key-order)
-;; or (setq which-key-sort-order 'which-key-description-order)
+;; same as default, except single characters are sorted alphabetically
+;; (setq which-key-sort-order 'which-key-key-order-alpha)
+;; same as default, except all prefix keys are grouped together at the end
+;; (setq which-key-sort-order 'which-key-prefix-then-key-order)
+;; sort based on the key description ignoring case
+;; (setq which-key-sort-order 'which-key-description-order)
 #+END_SRC
 
-The only other built-in option at the moment (besides using nil to turn off
-sorting completely) is =which-key-description-order=, which orders by the key's
-description based on the usual ordering of strings after applying =downcase=.
-
 *** Paging Options
 There are at least several prefixes that have many keys bound to them, like
 =C-x=. which-key displays as many keys as it can given your settings, but for

diff --git a/which-key.el b/which-key.el
index 45d509929b4f8a9ad6edeb0dbe10e1cc7eb8d5e6..81f6b272f7a3081d7244e2a903c5871ab2df0d88 100644 (file)
--- a/which-key.el
+++ b/which-key.el
@@ -934,6 +934,103 @@ width) in lines and characters respectively."
 width) in lines and characters respectively."
   (cons which-key-frame-max-height which-key-frame-max-width))
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Sorting functions
+
+(defun which-key--alpha< (a b)
+  (let ((da (downcase a))
+        (db (downcase b)))
+    (if (string-equal da db)
+        (not (string-lessp a b))
+      (string-lessp da db))))
+
+(defun which-key--key-description-alpha< (a b)
+  "Sorting function used for `which-key-key-order-alpha'."
+  (let* ((aem? (string-equal a ""))
+         (bem? (string-equal b ""))
+         (a1? (= 1 (length a)))
+         (b1? (= 1 (length b)))
+         (srgxp "^\\(RET\\|SPC\\|TAB\\|DEL\\|LFD\\|ESC\\|NUL\\)")
+         (asp? (string-match-p srgxp a))
+         (bsp? (string-match-p srgxp b))
+         (prrgxp "^\\(M\\|C\\|S\\|A\\|H\\|s\\)-")
+         (apr? (string-match-p prrgxp a))
+         (bpr? (string-match-p prrgxp b)))
+    (cond ((or aem? bem?) (and aem? (not bem?)))
+          ((and asp? bsp?)
+           (if (string-equal (substring a 0 3) (substring b 0 3))
+               (which-key--key-description< (substring a 3) (substring b 3))
+             (string-lessp a b)))
+          ((or asp? bsp?) asp?)
+          ((and a1? b1?) (which-key--alpha< a b))
+          ((or a1? b1?) a1?)
+          ((and apr? bpr?)
+           (if (string-equal (substring a 0 2) (substring b 0 2))
+               (which-key--key-description< (substring a 2) (substring b 2))
+             (string-lessp a b)))
+          ((or apr? bpr?) apr?)
+          (t (string-lessp a b)))))
+
+(defsubst which-key-key-order-alpha (acons bcons)
+  "Order key descriptions A and B.
+Order is lexicographic within a \"class\", where the classes and
+the ordering of classes are listed below.
+
+special (SPC,TAB,...) < single char < mod (C-,M-,...) < other.
+Sorts single characters alphabetically with lowercase coming
+before upper."
+  (which-key--key-description-alpha< (car acons) (car bcons)))
+
+(defun which-key--key-description< (a b)
+  "Sorting function used for `which-key-key-order'."
+  (let* ((aem? (string-equal a ""))
+         (bem? (string-equal b ""))
+         (a1? (= 1 (length a)))
+         (b1? (= 1 (length b)))
+         (srgxp "^\\(RET\\|SPC\\|TAB\\|DEL\\|LFD\\|ESC\\|NUL\\)")
+         (asp? (string-match-p srgxp a))
+         (bsp? (string-match-p srgxp b))
+         (prrgxp "^\\(M\\|C\\|S\\|A\\|H\\|s\\)-")
+         (apr? (string-match-p prrgxp a))
+         (bpr? (string-match-p prrgxp b)))
+    (cond ((or aem? bem?) (and aem? (not bem?)))
+          ((and asp? bsp?)
+           (if (string-equal (substring a 0 3) (substring b 0 3))
+               (which-key--key-description< (substring a 3) (substring b 3))
+             (string-lessp a b)))
+          ((or asp? bsp?) asp?)
+          ((and a1? b1?) (string-lessp a b))
+          ((or a1? b1?) a1?)
+          ((and apr? bpr?)
+           (if (string-equal (substring a 0 2) (substring b 0 2))
+               (which-key--key-description< (substring a 2) (substring b 2))
+             (string-lessp a b)))
+          ((or apr? bpr?) apr?)
+          (t (string-lessp a b)))))
+
+(defsubst which-key-key-order (acons bcons)
+  "Order key descriptions A and B.
+Order is lexicographic within a \"class\", where the classes and
+the ordering of classes are listed below.
+
+special (SPC,TAB,...) < single char < mod (C-,M-,...) < other."
+  (which-key--key-description< (car acons) (car bcons)))
+
+(defsubst which-key-description-order (acons bcons)
+  "Order descriptions of A and B.
+Uses `string-lessp' after applying lowercase."
+  (string-lessp (downcase (cdr acons)) (downcase (cdr bcons))))
+
+(defun which-key-prefix-then-key-order (acons bcons)
+  "Order first by whether A and/or B is a prefix with no prefix
+coming before a prefix. Within these categories order using
+`which-key-key-order'."
+  (let ((apref? (which-key--group-p (cdr acons)))
+        (bpref? (which-key--group-p (cdr bcons))))
+    (if (not (eq apref? bpref?))
+        (and (not apref?) bpref?)
+      (which-key-key-order acons bcons))))
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Functions for retrieving and formatting keys
 
@@ -1097,100 +1194,6 @@ alists. Returns a list (key separator description)."
          (list key-w-face sep-w-face desc-w-face)))
      unformatted)))
 
-(defun which-key--alpha< (a b)
-  (let ((da (downcase a))
-        (db (downcase b)))
-    (if (string-equal da db)
-        (not (string-lessp a b))
-      (string-lessp da db))))
-
-(defun which-key--key-description-alpha< (a b)
-  "Sorting function used for `which-key-key-order-alpha'."
-  (let* ((aem? (string-equal a ""))
-         (bem? (string-equal b ""))
-         (a1? (= 1 (length a)))
-         (b1? (= 1 (length b)))
-         (srgxp "^\\(RET\\|SPC\\|TAB\\|DEL\\|LFD\\|ESC\\|NUL\\)")
-         (asp? (string-match-p srgxp a))
-         (bsp? (string-match-p srgxp b))
-         (prrgxp "^\\(M\\|C\\|S\\|A\\|H\\|s\\)-")
-         (apr? (string-match-p prrgxp a))
-         (bpr? (string-match-p prrgxp b)))
-    (cond ((or aem? bem?) (and aem? (not bem?)))
-          ((and asp? bsp?)
-           (if (string-equal (substring a 0 3) (substring b 0 3))
-               (which-key--key-description< (substring a 3) (substring b 3))
-             (string-lessp a b)))
-          ((or asp? bsp?) asp?)
-          ((and a1? b1?) (which-key--alpha< a b))
-          ((or a1? b1?) a1?)
-          ((and apr? bpr?)
-           (if (string-equal (substring a 0 2) (substring b 0 2))
-               (which-key--key-description< (substring a 2) (substring b 2))
-             (string-lessp a b)))
-          ((or apr? bpr?) apr?)
-          (t (string-lessp a b)))))
-
-(defsubst which-key-key-order-alpha (acons bcons)
-  "Order key descriptions A and B.
-Order is lexicographic within a \"class\", where the classes and
-the ordering of classes are listed below.
-
-special (SPC,TAB,...) < single char < mod (C-,M-,...) < other.
-Sorts single characters alphabetically with lowercase coming
-before upper."
-  (which-key--key-description-alpha< (car acons) (car bcons)))
-
-(defun which-key--key-description< (a b)
-  "Sorting function used for `which-key-key-order'."
-  (let* ((aem? (string-equal a ""))
-         (bem? (string-equal b ""))
-         (a1? (= 1 (length a)))
-         (b1? (= 1 (length b)))
-         (srgxp "^\\(RET\\|SPC\\|TAB\\|DEL\\|LFD\\|ESC\\|NUL\\)")
-         (asp? (string-match-p srgxp a))
-         (bsp? (string-match-p srgxp b))
-         (prrgxp "^\\(M\\|C\\|S\\|A\\|H\\|s\\)-")
-         (apr? (string-match-p prrgxp a))
-         (bpr? (string-match-p prrgxp b)))
-    (cond ((or aem? bem?) (and aem? (not bem?)))
-          ((and asp? bsp?)
-           (if (string-equal (substring a 0 3) (substring b 0 3))
-               (which-key--key-description< (substring a 3) (substring b 3))
-             (string-lessp a b)))
-          ((or asp? bsp?) asp?)
-          ((and a1? b1?) (string-lessp a b))
-          ((or a1? b1?) a1?)
-          ((and apr? bpr?)
-           (if (string-equal (substring a 0 2) (substring b 0 2))
-               (which-key--key-description< (substring a 2) (substring b 2))
-             (string-lessp a b)))
-          ((or apr? bpr?) apr?)
-          (t (string-lessp a b)))))
-
-(defsubst which-key-key-order (acons bcons)
-  "Order key descriptions A and B.
-Order is lexicographic within a \"class\", where the classes and
-the ordering of classes are listed below.
-
-special (SPC,TAB,...) < single char < mod (C-,M-,...) < other."
-  (which-key--key-description< (car acons) (car bcons)))
-
-(defsubst which-key-description-order (acons bcons)
-  "Order descriptions of A and B.
-Uses `string-lessp' after applying lowercase."
-  (string-lessp (downcase (cdr acons)) (downcase (cdr bcons))))
-
-(defun which-key-prefix-then-key-order (acons bcons)
-  "Order first by whether A and/or B is a prefix with no prefix
-coming before a prefix. Within these categories order using
-`which-key-key-order'."
-  (let ((apref? (which-key--group-p (cdr acons)))
-        (bpref? (which-key--group-p (cdr bcons))))
-    (if (not (eq apref? bpref?))
-        (and (not apref?) bpref?)
-      (which-key-key-order acons bcons))))
-
 (defun which-key--get-formatted-key-bindings ()
   "Uses `describe-buffer-bindings' to collect the key bindings in
 BUFFER that follow the key sequence KEY-SEQ."